GSM AI 해커톤 - 실습 코드 템플릿 및 단계별 검증 가이드

이 패키지는 광주소프트웨어마이스터고등학교(GSM) AI 해커톤 교육 과정의 실습 코드 세트입니다.
AWS EC2 인프라 설정부터 S3 연동, 로컬 벡터 DB(FAISS) 구축, Amazon Bedrock(Claude 5) 호출 및 Streamlit 실시간 웹 챗봇 최종 배포까지 모든 단계의 코드와 검증 명령어를 제공합니다.

파일 목록 및 역할

1. requirements.txt: 실습에 필요한 파이썬 라이브러리 목록 및 고정 버전
2. bedrock_simple_test.py: EC2의 IAM 인스턴스 프로파일 권한 및 Bedrock Claude 5 연동을 점검하는 기초 파일
3. bedrock_faiss_indexer.py: S3 버킷에서 문서를 다운로드하여 잘게 쪼갠 후 로컬 벡터 데이터베이스(FAISS)로 저장하는 인덱서 파일 (Day 2)
4. bedrock_faiss_rag_chatbot.py: 로컬 벡터 DB에서 고속 의미 검색을 수행한 뒤 Claude 5와 연동해 답변하는 CLI 챗봇 파일 (Day 2)
5. app.py: 최종 결과물인 Streamlit 웹 기반 실시간 스트리밍 답변 RAG 챗봇 어플리케이션 (Day 3)

단계별 실행 및 접속 검증 명령어 가이드

아래 단계들은 우분투 EC2 인스턴스에 접속한 후 순서대로 실행하며 테스트를 검증하는 용도입니다.

[Step 1] 시스템 패키지 및 AWS CLI 설치 검증

우분투 서버 내에 AWS CLI가 올바르게 설치되었는지 검증합니다.

• 설치 명령어:

  sudo apt-get update
  sudo apt-get install -y unzip curl
  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
  unzip awscliv2.zip
  sudo ./aws/install
  

• 검증 명령어:

  aws --version
  

• 정상 결과 예시:
  aws-cli/2.x.x Python/3.x.x Linux/... 와 같이 버전 정보가 나타나면 성공입니다.

[Step 2] EC2 IAM 인스턴스 프로파일(Role) 권한 검증

EC2가 비밀키 입력 없이 올바른 IAM 역할을 할당받았는지 확인합니다.

• 검증 명령어:

  aws sts get-caller-identity
  

• 정상 결과 예시:
  출력되는 JSON 내의 Arn이 arn:aws:sts::498307943987:assumed-role/gsm-student-role/... (또는 gsm-instructor-role) 형태의 Role ARN으로 나타나야 합니다. (Access Key/Secret Key가 등록되어 있지 않아도 정상 조회되어야 함)

[Step 3] S3 버킷 연동 및 권한 검증

EC2에서 S3 버킷의 파일 목록을 조회하거나 업로드가 정상적으로 가능한지 확인합니다.

• 조회 검증 명령어:

  # 강사용 버킷 혹은 본인 서브넷 소유의 학생용 버킷 조회
  aws s3 ls s3://gsm-instructor-bucket-tbit-498307943987/
  

• 업로드 테스트 명령어:

  echo "EC2-to-S3 Connection Check" > connection_test.txt
  aws s3 cp connection_test.txt s3://gsm-instructor-bucket-tbit-498307943987/
  

• 정상 결과 예시:
  에러 메시지(AccessDenied) 없이 파일 목록이 출력되거나 업로드 완료 메시지가 출력되면 성공입니다.

[Step 4] 파이썬 실습 패키지 전역 설치

파이썬 패키지를 서버 전역 환경에 안전하게 강제 설치합니다.

• 설치 명령어:

  pip3 install -r requirements.txt --break-system-packages
  

• 검증 명령어:

  pip3 list | grep -E "langchain|faiss|streamlit|boto3"
  

• 정상 결과 예시:
  boto3, faiss-cpu, langchain, langchain-aws, streamlit 등의 패키지 버전들이 화면에 출력되어야 합니다.

[Step 5] Bedrock Claude 5 API 연동 검증

가장 기초적인 Bedrock API 다이렉트 호출 테스트를 수행합니다.

• 실행 명령어:

  python3 bedrock_simple_test.py
  

• 정상 결과 예시:
  --- Claude Response --- 문구 하단에 Claude 5가 작성한 "연동 성공을 축하합니다!" 관련 한 줄짜리 한국어 답변이 무사히 출력되면 성공입니다.

[Step 6] 로컬 벡터 DB(FAISS) 빌드 및 검증

S3 문서 다운로드 및 쪼개기(Chunking) 후 로컬 벡터 데이터베이스가 생성되는지 검증합니다.

• 실행 명령어:

  python3 bedrock_faiss_indexer.py
  

• 인덱스 폴더 생성 검증:

  ls -la faiss_index/
  

• 정상 결과 예시:
  index.faiss와 index.pkl 파일이 들어있는 faiss_index/ 폴더가 EC2 디렉토리에 정상적으로 생성되어야 합니다.

[Step 7] 로컬 RAG CLI 챗봇 구동 및 환각 방어 검증

로컬 DB를 검색하여 답변하는 터미널 챗봇을 실행하고, RAG가 올바르게 작동하는지 퀴즈를 냅니다.

• 실행 명령어:

  python3 bedrock_faiss_rag_chatbot.py
  

• 검증 질문 세트:
  1. Q: 교육 일정에 대해서 알려줘
     👉 정상 답변: "2026년 7월 15일부터 17일까지 총 3일간 진행됩니다" 등 S3 원천 데이터의 팩트가 대답되어야 합니다.
  2. Q: 파리 날씨는 어때?
     👉 정상 답변: "참고문서에 관련 정보가 없어 답변드리기 어렵습니다"와 같이, 가짜 지식을 지어내지 않고 정중하게 답변을 거부(환각 방지)해야 합니다.
  • 종료하려면 exit를 입력해 종료합니다.

[Step 8] Streamlit 웹 RAG 애플리케이션 가동 및 포트 검증

Day 3의 최종 결과물인 웹 화면 UI 상에 RAG 챗봇 및 S3 문서 업로드 포털 서비스를 띄웁니다.

• 웹 서버 기동 명령어:

  # 기본 포트(8501)로 가동
  python3 -m streamlit run app.py --server.address 0.0.0.0
  

• 서버 바인딩 포트 확인 명령어:

  sudo netstat -tulpn | grep -E "8501"
  

• 정상 결과 예시:
  웹 브라우저 주소창에 http://<EC2-퍼블릭-IP>:8501을 입력했을 때, 다중 페이지(💬 RAG 챗봇 및 📁 S3 문서 업로드 & DB 갱신) 형태의 포털 화면이 표시되어야 합니다.
  • 새로운 문서를 업로드하고 즉시 FAISS DB를 갱신한 후 챗봇을 테스트할 수 있습니다.

[Step 9] Streamlit 백그라운드 상시 구동 및 관리 (SSH 종료 후 유지)

SSH 터미널 세션을 종료하더라도 웹 서버가 계속 가동되도록 백그라운드로 실행하는 방법입니다.

방법 A: nohup 사용 (추천 - 단일 명령어로 간편함)

• 백그라운드 실행:

  nohup python3 -m streamlit run app.py --server.address 0.0.0.0 > streamlit.log 2>&1 &
  

• 로그 확인 (실시간 출력):

  tail -f streamlit.log
  

• 서버 종료 방법:
  • 가장 쉬운 한 줄 종료 (추천 🌟):

    pkill -f streamlit
    

  • 프로세스 번호(PID) 조회 후 수동 종료:

    # 1) 백그라운드 프로세스 ID(PID) 확인
    ps -ef | grep streamlit
    
    # 2) 확인된 PID 종료 (예: PID가 1234인 경우)
    kill -9 1234
    

방법 B: screen 사용 (리눅스 가상 스크린 터미널)

• 새로운 가상 스크린 생성:

  screen -S streamlit_session
  

• 스크린 내부에서 실행:

  python3 -m streamlit run app.py --server.address 0.0.0.0
  

• 백그라운드로 빠져나오기 (백그라운드 유지):
  • 키보드 단축키: Ctrl + A를 누른 뒤 순서대로 D 키를 누릅니다. ([detached] 메시지가 출력됨)
• 다시 스크린 화면으로 들어가기:

  screen -r streamlit_session
  

• 서버 종료 방법:
  • 스크린 내부 세션으로 진입하여 Ctrl + C로 중단한 후 exit를 입력해 세션을 소멸시킵니다.